Summary

Add docs/release-artifact.md, a new reference document covering the on-disk formats that had no dedicated documentation after the v1.1 rollout. Update docs/operations-and-policy.md with a flightdeck doctor section and a cross-reference to the new doc. Update README.md to link the new page.

Why

After the v1.1 docs push (HTTP API, SDK, operations/policy), three important subsystems still had no reference page:

• The release.yaml schema (all spec sub-models: routing, safety, tools, prompts, tags) had no field-level docs
• The workspace config (flightdeck.yaml) was referenced everywhere but never documented
• Pricing table YAML format, --replace/--reason semantics, and pricing_import_audit were undocumented
• flightdeck doctor and its three checks had no operational runbook entry

Changes

docs/release-artifact.md (new, 216 lines):

• release.yaml full field reference with all optional spec sub-models
• Bundle directory layout and which files are excluded from checksum
• Bundle checksum algorithm: file collection, sort order, CRLF normalization, hash construction
• flightdeck.yaml (WorkspaceConfig) field reference with defaults and relationship to policy min_* overrides
• Pricing table YAML format with all rate fields and cached_input_usd_per_1k_tokens optional field
• flightdeck pricing import / --replace / --reason semantics and the pricing_import_audit table
• Pricing accuracy note: cross-release pricing_reference differences and pricing_or_model_changed flag

docs/operations-and-policy.md (updated):

• Added opening cross-reference to release-artifact.md
• Added flightdeck doctor section covering the three checks (schema_migrations, promoted_pointer, audit_seq), example output, exit behavior, and audit_seq gap-detection semantics

README.md (updated):

• Added link to docs/release-artifact.md in the Documentation section

Validation

• uv sync --frozen --extra dev
• uv run python -m ruff check src tests
• uv run python -m pytest
• uv run python scripts/generate_schemas.py then git diff --exit-code schemas/ (if models/schemas touched)
• cd web && npm ci && npm run build && cd .. && git diff --exit-code src/flightdeck/server/static/ (if web/src/ or deps changed)
• uv run flightdeck-quickstart-verify
• uv run flightdeck --help

This PR is docs-only; no Python source, schemas, or web assets were modified.

Schema / Storage Impact

• None

Risk

Documentation only. No code changes. All content was verified against the actual source (src/flightdeck/bundle.py, models.py, config.py, doctor.py, storage.py, cli/main.py).

Notes

Covers the knowledge gaps identified by comparing the v1.1 codebase to the docs that shipped with it.